# System commands

System commands control the q environment. They have the form:

\cmd [p]
for some command cmd, and optional parameter list p.

Commands with optional parameters that set values, will show the current values if the parameters are elided.

Some system commands have equivalent command-line parameters.

Call a system command in a q expression

To call a system command in a q expression, use system.

q)\l sp.q
...
q)\a                     / tables in namespace
pssp
q)count \a               / \ must be the first character
'\
q)system "a"             / same command called with system
pssp
q)count system "a"       / this returns a result
3

## \a – tables¶

Syntax: \a

Syntax: \a [namespace]

Lists tables in the given namespace, default current namespace.

q)\a
symbol$() q)aa:bb:23 q)\a symbol$()
q)tt:([]dd:12 34)
q)\a
,tt
q).nn.vv:([]uu:12 45)
q)\a
,tt
q)\a .n
'.n
q)\a .nn
,vv
q)\d .nn
q.nn)\a
,vv
q.nn)vv
uu
--
12
45
q.nn)

## \b – views¶

Syntax: \b [namespace]

Lists all dependencies (views).

q)a::x+y
q)b::x+1
q)\b
s#ab
.z.b.

## \B – pending views¶

Syntax: \B [namespace]

Lists all pending dependencies (views), i.e. dependencies not yet referenced, or not referenced after their referents have changed.

q)a::x+1          / a depends on x
q)\B              / the dependency is pending
,a
q)x:10
q)\B              / still pending after x is defined
,a
q)a               / use a
11
q)\B              / no longer pending
symbol$() ## \c – console size¶ Syntax: \c Syntax: \c [h,w] Sets console height and width. This is the same as the -c command line parameter. These settings determine when q elides output with .. Note You usually don't need to set this. If the environment variables LINES and COLUMNS are found they'll be taken as the default value. See Bash documentation for shopt parameter checkwinsize to make sure they're reset as needed. q)\c 45 160 q)\c 5 5 q)\c 10 10 q)til each 20+til 10 0 1 2 3.. 0 1 2 3.. 0 1 2 3.. 0 1 2 3.. 0 1 2 3.. 0 1 2 3.. 0 1 2 3.. .. ## \C – HTTP size¶ Syntax: \C [h,w] Sets the HTTP height and width. This is the same as command-line option -C. ## \cd – change directory¶ Syntax: \cd [name] Changes the current directory. ~/q$ q
KDB+ 2.6 2010.05.10 Copyright (C) 1993-2010 Kx Systems
..
q)\cd
"/home/guest/q"
q)\cd /home/guest/dev
q)\cd
"/home/guest/dev"

## \d – directory¶

Syntax: \d [namespace]

Sets the current namespace (also known as directory or context). The namespace can be empty, and a new namespace is created when an object is defined in it. The prompt indicates the current namespace.

q)\d                  / default namespace
.
q)\d .o               / change to .o
q.o)\f
ColsColumnsFGFkeyGkeyKeySpecial..
q)key                / lists namespaces other than .z
qQoh
q)\d .s               / change to non-existent namespace
q.s)key              / not yet created
qQoh
q.s)a:1               / create object, also creates namespace
q.s)key
qQohs

## \e – error trap clients¶

Syntax: \e [0|1]

This enables error trapping for client requests. The default is 0 (off).

When a client request has an error, by default the server clears the stack. This is appropriate for production use as it enables the server to continue processing other client requests.

For development, you can set \e 1 to enable debugging on the server. In this case, the server suspends on an error, and does not process other requests until the stack is cleared.

## \f – functions¶

Syntax: \f [namespace]

Lists functions in the given namespace, default current namespace.

q)f:g:h:{x+2*y}
q)\f
fgh
q)\f .h
cdcodedataebecedesestrframhahbhchehnhphrhthtahtachtchtmlhttphuhughyjxnbrpretdtextuhxdxmpxsxt
q){x where x like"ht??"}system"f .h"
htachtmlhttp

## \g – garbage collection mode¶

Syntax: \g [mode]

Since V2.7 2011.02.04. Switch garbage collection between immediate (1) and deferred (0) modes.
-g command-line option

## \l – load file or directory¶

Syntax: \l name

The parameter can be a script filename or a directory. A script is loaded, and a directory database is opened. When q opens a directory, it changes its current directory to it. This allows reloading the current database using \l .. If the directory is specified as ., any scripts in that directory will be ignored; this is to allow (re)loading of data only.

q)\l sp.q            / load sp.q script
...
q)\a                 / tables defined in sp.q
pssp
q)\l db/tickdata     / load the data found in db/tickdata
q)\a                 / with tables quote and trade
pquotessptrade

## \o – offset from UTC¶

Syntax: \o [n]

Sets the local time offset, as hours from UTC, or as minutes if abs[n]>23. Initially, the value is 0N, meaning that the machine's offset is used.

q)\o
0N
q).z.p                        / UTC
2010.05.31D23:45:52.086467000
q).z.P                        / local time is UTC + 8
2010.06.01D07:45:53.830469000
q)\o -5                       / set local time as UTC - 5
q).z.P
2010.05.31D18:45:58.470468000
q)\o 390                      / set local time as UTC + 6:30
q).z.P
2010.06.01D06:16:06.603981000
This corresponds to the -o command line parameter.

## \p – port¶

Syntax: \p [i]

Sets the listening port number. The default is 0 (no listening port). The port must be available and the process must have permission for the port.

A negative parameter sets a multi-threaded port and if used it must be the initial and only mode of operation, i.e. do not dynamically switch between positive port and negative port.

A parameter of 0W means pick a random available port within the range 32768 - 60999.

q)\p 5010     / set port 5010
q)\p
5010
q)\p 0W       / pick a random available port within the range 32768 - 60999
q)\p
45512
q
q)\p 0        / turn off listening port
This corresponds to the -p command line parameter.

## \P – precision¶

Syntax: \P [n]

Sets display precision for floating point numbers, i.e. the number of digits shown.
-P command-line option

## \r – replication master¶

Syntax: \r

This should not be executed manually otherwise it can disrupt replication. It is executed automatically by the replicating process on the master process, and returns the log file name and log file count.
-r command-line option

## \r – rename¶

Syntax: \r src dst

This renames file src to dst. It is equivalent to the Unix mv command, or the windows move command (except that it will not rename to a different disk drive).

## \s – number of slaves¶

Syntax: \s

This queries the number of slaves, set with the -s command line parameter (query only).

## \S – random seed¶

Syntax: \S [n]

Sets the random number seed. The parameter must be a non-zero integer. Note that \S is not updated as the random-number generator is used.

q)\S              / default
-314159
q)5?10
8 1 9 5 4
q)5?10
6 6 1 8 5
q)\S -314159      / restore default seed
q)5?10            / same random numbers generated
8 1 9 5 4
q)\S              / seed is not updated
-314159

Note

Since V3.1 2013.08.19 the behaviour is as follows.

Rng is thread-local. \S 1234 sets the seed for the rng for the main thread only. The rng in a slave thread is assigned a seed based on the slave thread number. In multithreaded input mode, the seed is based on socket descriptor. Instances started on ports 20000 thru 20099 (slave procs, used with e.g. q -s -4 have the main thread’s default seed based on the port number.

## \t – timer¶

Syntax: \t [p]

This command has two different uses depending on the parameter given.

An integer parameter is the number of milliseconds between timer ticks. If 0, the timer is turned off, otherwise the timer is turned on and the first tick given. On each tick, the function assigned to .z.ts is executed.

q)\t                           / default off
0
2010.06.01
q)\z 1
q)"D"$"06/01/2010" 2010.01.06 ## \1 & \2 – redirect¶ Syntax: \1 filename Syntax: \2 filename \1 and \2 allow redirecting stdout and stderr to files from within the q session. The files and intermediate directories are created if necessary. ~/q$ rm -f t1.txt t2.txt
~/q$l64/q KDB+ 2.6 2010.05.10 Copyright (C) 1993-2010 Kx Systems ... q)\1 t1.txt / stdout q)\2 t2.txt / stderr til 10 2 + "hello" \\ ~/q$ cat t1.txt          / entry in stdout
0 1 2 3 4 5 6 7 8 9
~/q$l64/q KDB+ 2.6 2010.05.10 Copyright (C) 1993-2010 Kx Systems .. q)\_ t1.q / create locked script t1.q_ q)\l t1.q_ / can be loaded as usual q)a / definitions are correct 123 q)f[10;1 2 3] 12 14 16 q)f / q code cannot be displayed locked q)-8!f / or serialized 'type q)read1:t1.q_ / file contents are scrambled 0x27fc45d98727b2ed0a530c25881733a5 ## \ – terminate¶ If there is a suspension, this exits one level of the suspension. Otherwise, it toggles between q and k mode. (To switch languages from inside a suspension, type "\".) q){1+x}"hello" {1+x} 'type + 1 "hello" q))\ / clear suspension (only one level) q)\ / toggle to k mode !5 0 1 2 3 4 \ / toggle to q mode q) ## \ – toggle q/k¶ In the interactive session \ toggles between the q and k interpreters. q)\ \ q) ## \\ – quit¶ Syntax: \\ • In the interactive session type \\ at the prompt to quit the session. • Inside a function, use value"\\\\" or exit 0 for the same result. exit, value Tip The text following \\ and white space is ignored by q. This is often useful in scripts where \\ can be followed by comments or usage examples. ## OS Commands¶ If an expression begins with \ but is not recognized as a system command, then it is executed as an OS command. q)\ls / usual ls command "help.q" "k4.lic" "l64" "odbc.k" "profile.q" "q.k" .. Warning This means that typos can get passed to the OS. When you are run rm -r / you are have of many problem, but Big Data is not of one of them. — DevOps Borat ## system¶ Syntax: system x where x is a system command, executes it and returns its result. The following shows that the result of \w (workspace information) cannot be assigned, but the result can be obtained using system. q)\w 107728 67108864 67108864 0 0j q)a:\w 'w q)a:system "w" q)a 107872 67108864 67108864 0 0j As with \, if the argument is not a q command, it is executed in the shell: q)system "pwd" "/home/guest/q" Directing output to a file When redirecting output to a file, for efficiency purposes, avoiding using /tmp needlessly, append a semi-colon to the command. q)system"cat x" is essentially the same as the shell command$cat x > tmpout
as q tries to capture the output.
So if you do
q)system"cat x > y"
under the covers that looks like
$cat x > y > tmpout not good. So if you add the semi colon q)system"cat x > y;" the shell interpreter considers it as 2 statements$cat x > y; > tmpout

Capture stderr output

Can I capture the stderr output from the system call? Not directly, but a workaround is

/ force capture to a file, and cat the file
q)system"ls egg > file 2>&amp;1;cat file"
"ls: egg: No such file or directory"

/ try and fails to capture the text
q)@[system;"ls egg";{0N!"error - ",x;}]
ls: egg: No such file or directory
"error - os"

Changing working directory in Windows

In the event of an unexpected change to the working directory, Windows users please note http://blogs.msdn.com/b/oldnewthing/archive/2007/11/21/6447771.aspx