Page 1 of 1

Tips on usage (did you know that?..)

PostPosted: Mon Jan 30, 2012 7:07 pm
by Oleg
32-bit (x86) version of qinsightpad is working on MacOS under the following Wine port:

32-bit (x86) version of qinsightpad is working on Linux under the Wine.
Most annoying thing is anything using file open/save dialogs isn't working (always returning default filepath)
Workaround: Open files by dragging into qpad window or double-clicking in File Explorer pane. Save will work (Save As... won't)

Custom Query Wrapping (and what's it for):
Simple example - let's say you don't want to get results bigger than 15MB (in unpacked IPC size), following prefix will do it for you:
(15 can be changed to whatever limit you want, of course)
Code: Select all
{$[(y*1024*1024)<-22!x;'"Result is bigger than ",string[y],"MB";x]}[;15]{

Code: Select all

Go to Q->Settings->Editor tab, check Wrap queries in: box, paste those to Prefix and Postfix edits and press OK.
Now if results of any query you'll run are bigger than 15MB you'll get:
ERROR: 'Result is bigger than 15MB
(user-defined signal)

Feel free to share other useful things custom query wrapping can be used for.

Stateful Debugger/Interpreter (the one and only ;-)):
(Please make sure you've got latest devbuild from What's Cooking post - this stuff is work in progress, so devbuild will probably have a lot of fixes/improvements included)
Don't inject/use debugger on critical/sensitive instances, ideally use your own dev-instances.

QPad includes this brilliant piece of work done by Andrey Kozyrev in injectable form and provides GUI that I've tried to keep within traditional visual debugger paradigm.
Unlike buit-in command-line debugger it doesn't cripple instance operating capacity while you're using it - you can think of it as of stateful q step-by-step interpreter (written in q) that is busy only while you're taking a step through the code and available for other queries once step was performed and GUI's awaiting your input.

If you want to start new debugging session, select call that you want to debug in source window and press Ctrl+Alt+D
If you want to reset debugging session while in debugger dialog - press Prepare (you can also edit call you will be debugging to your liking before that)

You are able to see source of the current function and state of local variables in it at the point of execution or
- any function and its local context in a call-stack - by double-clicking on it in stack list
- any function you've set breakpoint in - by double-clicking on it in breakpoint list
- any other function by pressing Show function... button and typing full function name or right-clicking function node in Namespaces view and choosing Switch to in Debugger
- return to current function by double-clicking top (synthetic) line in a Stack

Stack contains not only functions, but operations arguments as well - go through some long arithmetic lines using Single-Step (Alt+F11) button watching stack and it'll make sense to you more quickly than you expect :).
To avoid confusion though, keep in mind that top line of the stack is synthetic - corresponding to current function, real top of the stack is below it.

If you want to watch globals - you can use watch pane (it's detachable) from main qpad window, it will auto-refresh with every step you'll take in debugger.
In general you can run whatever queries you like in main window of qpad, current local variables though aren't directly available, of course, but you can get/use them through .z.deb.a`localvarname. (That being said, only locals at a current point of execution will be available this way, no matter where you'll switch debugger context to)

Don't interpret flag is for situations when you want to go quickly through time-consuming operations (you know are alright, don't want to go inside them, don't want to catch signals from them).

Timeout is an internal debugger timeout one step/operation should obey (in order to keep instance alive).

Most interesting thing is number of handled signals to ignore.
Let's say you're dealing with the piece of code that uses protected execution and ignores some signals.
Something is askew there and you can't help but wonder if error-suppression got something to do with it...
- If you'll go/run through a signal being thrown and handled, this counter will be decremented by one.
- If you want to stop on signal even if it's handled - put 0 there, switch focus to source and go
- If after examination this place seems to be ok, but you are not sure about the next one - put 1 there, switch focus and go
(you'll pass this one, counter will be reduced to 0 - ensuring you'll be stopping on next one)

- You can rearrange, remove/add buttons and change keyboard shortcuts to your liking using View->Toolbars and Docking Windows->Customize...

- With customize dialog on screen you can click on Quick-connect combo and then resize it to your liking by right border

- Keep in mind that quick-connect is a combo - you can type/edit symbol there and connect/switch instance by pressing Enter (or (Dis)connected button), history is tracked in drop-down list of combo - can be cleared by pressing Q->Settings->Clear connect history button.

Source window:
- syntax highlighting while slow on big files could be made less painful by setting typing delay from 0 to 500 or so ms on Q->Settings->Editor tab
It would mean that while you're typing with less than set delay between chars, qpad won't try to re-color source. Also whatever typed in one go will be put to undo/redo stack as a whole.

- It is possible to tie source pane to q instance, to do so - go to Q->Settings->Editor tab and check Switch connections on pane activation
Keep in mind that it's
- not persisted between sessions
- setting symbol for a pane
1) when you're connecting to symbol being on a pane
2) first time switching to a pane or opening a file being connected somewhere
- switching connection when you're switched to a pane with different symbol (doesn't add it to history)
- shouldn't connect anywhere if you're disconnected (manually or for any other reason)

- You can color source pane background differently when you connected to sensitive/critical instances. To do so go to Q->Settings->Editor tab and edit what's in Critical instances group box:
Substrings are searched for in symbol itself as well as in the Server tree path.
Ex.: PROD;333 will match all instances listed under PROD folder (or wherever there's *PROD* in the path) and all ports or hostnames containing 333 and vice versa.

- You can highlight all selected substrings (identifiers or code fragment) in a source pane, by pressing Ctrl+M with desired substring selected (or cursor on a desired identifier)

- You can jump to other bracket ([], (), {} - as highlighted) with Ctrl+]

- Shift+Ctrl+] is selecting text between (and including) the brackets

- Pressing F1 with cursor on keyword will try to open corresponding page of reference from in default web browser.

- Line wrapping could be turned on and off independently per source pane by pressing Ctrl+L (or Menu View->Line wrapping)

- Right-click menu contains couple of useful commands:
- Copy as String->Handle will copy selected text as a string to pass to handle (escaping all " in it) to clipboard
select from depth where any sym like/:("AB*";"*L")
will be copied as
"select from depth where any sym like/:(\"AB*\";\"*L\")"

- Copy as URL will copy selected text as an URL to query server via browser (or to insert in html) escaping all necessary chars.
Currently connected server/port is used, user/password and format is not inserted. If needed put it as
user:pass@ right after http://
[filename][.xls|.csv|.xml] right before ?
Ex.: http://localhost:60?select%20from%20dep ... 3B%22*L%22)

Namespace + Properties:
- Pressing Refresh button on Namespace pane toolbar is a good place to start using Namespace explorer with the instance you connected to (Auto-refreshing could be set up in Q->settings)

- Red ! on the left of lambda in Namespace tree means that not all referenced globals can be resolved by Namespace cross-reference engine
(Could be result of
- error (incl. raising signal using 'err instead of '`err)
- usage of hidden under .z user entity
- conditional usage of something not present in a namespaces)

- You can jump through the dependencies and back double-clicking on names in Referenced globals, Globals ref'd from nested, Globals ref'd by symbol or Used in functions sections of Properties and using Back/Forward Properties pane toolbar buttons to navigate along the path you've jumped. Query button will query entity you're on to the Output (grayed out for big/partitioned tables)

- For more thorough investigation and assistance in research of the tricky pieces of codebase, you can use namespace tree node Right-click->Show Callers/Show Dependencies...
This will invoke 3-pane dialog with tree of chosen dependencies on the left and code for parent and child nodes on the right (those will keep up with you as you select different nodes in the tree on the left) .
Name of the dependency will be highlighted in caller's code.

Output Grid:
As grid is virtual, and to make things faster, column sizes are not set automatically to fit any of values you can discover by scrolling down, only those presently on the screen. You can however auto-size columns for on-screen data anytime by pressing Ctrl+J.

Command line parameters:
There are 3 parameters qpad.exe accepts
--async (enables sync/async switch in menu, otherwise disabled to avoid confusion - you should really know what you are doing to enable it ;-))
--server:<serversymbol> (to force-connect to a given instance on a startup)
--profile:<registrybranch> (to store window layout/open tabs and settings)
Last two are used by qpad when launching instance from Server tree->Right-Click->Launch QPad (creates/uses separate profiles per server symbol)
Also you can use them to create shortcuts for different instances and/or UI tuned/colored and sets of q files opened for different tasks.

Could be setup to be updated manually/automatically (after each query)
Values highlighted if changed since last watches update
Only checked watches are updated
Lots of commands for disabling/enabling/querying to output/saving and loading list/etc. in pop-up menu (Right-click)
- Double-click on expression cell - edit it
- Double-click on value cell - query it to output
- Click on expression column header reverses checks

Watches are also updating on each step performed in debugger, making them handy to watch how globals are changing during debugging.

Config files
Are in plain text and in most readable/editable/generatable way possible on purpose:
Every line is
e.g. node symbol and node name with a full path between them, separated with `
There can't be empty folders in a tree after reload, but it's a small price to pay for plain and simple format
Any line can be commented out with # as a first char. Actually, right now it's any non-` char, but I reserve a right to use non-`&# leading chars for instance class (prod/dr/uat/dev/whatever) in the future.

BTW:When adding server nodes using interface, I left a short-cut to add whole chain of hierarchy you want between the folder you've right-clicked on & the new node.
Just use the same notation in server name field - `Folder1`Folder2...`NodeName

Every line is
Disabled in there's no leading tab (\t), enabled if there is.

File recovery on Windows 7 (probably Vista+, wouldn't work on XP)
If you using windows 7 and think you've lost some .q file from qpad, a place to look for it would be
there will be files like this:
file date/time will be helpful in recovering version you're looking for.

To be continued...