From Kx Wiki
Jump to: navigation, search


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.

The entry must begin with \. To call a system command in a q expression, use system, for example:

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

\a [namespace] - tables

Lists tables in the given namespace, default current namespace.

q)\l sp.q
q)\a                      / tables in default namespace
q)\a .o                   / tables in .o

\b - views/dependencies

Lists all dependencies (views). See also .z.b. For example:


\B - pending views/dependencies

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
q)\B                  / still pending after x is defined
q)a                   / use a
q)\B                  / no longer pending

\c [h,w] - console height,width

Sets console height and width. This is the same as the -c command line parameter, see Console Size

\C [h,w] - http height,width

Sets the http height and width. This is the same as the -C command line parameter, see Console Size

\cd [name] - change directory

Changes the current directory.
Warning.png Directory will be created if it doesn't exist.
~/q$ q
KDB+ 2.6 2010.05.10 Copyright (C) 1993-2010 Kx Systems
q)\cd /home/guest/dev

\d [namespace] - directory

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. For example:

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

\e [0|1] - error trap clients

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 [namespace] - functions

Lists functions in the given namespace, default current namespace.

q)\f .q

\g [mode] - garbage collection mode

Since 2.7 2011.02.04. Switch garbage collection between immediate (1) and deferred (0) modes. See also -g.

\l name - load file or directory

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
q)\l db/tickdata         / load the data found in db/tickdata
q)\a                     / with tables quote and trade

\o [n] - offset from GMT

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

q).z.p                            / GMT
q).z.P                            / local time is GMT + 8
q)\o -5                           / set local time as GMT - 5
q)\o 390                          / set local time as GMT + 6:30

This corresponds to the -o command line parameter.

\p [i] - port

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 0W           / pick a random available port within the range 32768 - 60999

q)\p 0            / turn off listening port

This corresponds to the -p command line parameter.

\P [n] - precision

Sets display precision for floating point numbers, i.e. the number of digits shown, see Display Precision.

\r - replication master

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 (see Command Line Reference).

\r src dst - rename

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

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

\S [n] - random seed

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
8 1 9 5 4
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

n.b. since kdb+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 [p] - timer

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
q)\t 1000                      / tick each second
\t 0                           / turn off

A parameter of a q expression other than a single integer is executed and the execution time shown in milliseconds.

q)\t log til 100000            / milliseconds for log of first 100000 numbers
q)\t do[100;log til 100000]    / timing for 100 repetitions
q)\t:100 log til 100000    / timing for 100 repetitions, new syntax of "\t:n expr" since 3.0 2011.11.22

The tick timer usage corresponds to the -t command line parameter.

\ts exp - time and space

Executes the expression and shows the execution time in milliseconds and the space used in bytes.

q)\ts log til 100000
7 2621568j

Since 3.1 2014.02.07

q)\ts:10000 log til 1000           /same as \ts do[10000; log til 1000]
329 24672

\T [n] - timeout

This sets the client execution timeout, as the integer number of seconds a client call will execute before timing out, default 0 (no timeout). Note that this is in seconds, not milliseconds like \t.

This corresponds to the -T command line parameter.

\u - reload user password file

When q is invoked with the -u parameter specifying a user password file, then \u will reload the password file. This allows updates to the password file while the server is running.

\v [namespace] - variables

Lists the variables in the given namespace, default current namespace.

q)\v .o

\w [0] - workspace

If there is no parameter, lists current memory usage, as a list of 6 long integers:

[0] number of bytes allocated
[1] bytes available in heap
[2] maximum heap size so far
[3] maximum bytes available, given in -w command line parameter
[4] mapped bytes
[5] physical memory

If there is a parameter, returns a pair:

[0] number of internalized symbols
[1] corresponding memory usage
168144 67108864 67108864 0 0 8589934592j
q)\w 0
577 25436j

The function .Q.w formats all this information:

used| 168304
heap| 67108864
peak| 67108864
wmax| 0
mmap| 0
mphy| 8589934592
syms| 577
symw| 25436

\W [n] - week offset

Specifies the start of week offset, where 0 is Saturday. The default is 2 = Monday.

This corresponds to the -W command line parameter.

\x .z.p* - expunge

By default, callbacks like .z.po are not defined in the session. After they have been assigned, you can restore the default using \x to delete the definition that was made.

q).z.pi                       / default has no user defined function
q).z.pi:{">",.Q.s value x}    / assign function
q)\x .z.pi                    / restore default

N.B. This works only for .z.p* variables defined in k before q.k is loaded. e.g. as is defined in q.k, there is no default for it to be reset to.

\z [0|1] - date parsing

Specifies the format for date parsing. 0 is "mm/dd/yyyy" and 1 is "dd/mm/yyyy".

q)\z 1

\1 & \2 filename - redirect

\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$ cat t2.txt          / entry in stderr

\_ [scriptname] - hide q code

This command has two different uses depending on whether a parameter is given.

If no parameter, then \_ checks if client write access is blocked, see -b.

If a parameter is given, it should be a scriptname and \_ f.q makes a runtime script f.q_. The q code cannot be viewed or serialized.

~/q$ echo "a:123;f:{x+2*y}" > t1.q
~/q$ l64/q
KDB+ 2.6 2010.05.10 Copyright (C) 1993-2010 Kx Systems
q)\_ t1.q               / create locked script
q)\l t1.q_              / can be loaded as usual
q)a                     / definitions are correct
q)f[10;1 2 3]
12 14 16
q)f                     / q code cannot be displayed
q)-8!f                  / or serialized
q)read1`:t1.q_          / file contents are scrambled

\ - 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))\                         / clear suspension (only one level)
q)\                          / toggle to k mode
0 1 2 3 4
  \                          / toggle to q mode

\\ - exit

Exit from q.

OS Commands

If an expression begins with \ but is not recognized as a system command, then it is executed as an OS command.

- this means that typos can get passed to the OS.
For example:
q)\ls                 / usual ls command
Personal tools