QforMortals2/commands and system variables

From Kx Wiki
Jump to: navigation, search

Contents

Commands and System Variables

Command Format

Commands control aspects of the q environment. A command begins with a back-slash (\) and is followed by one or more characters. Some commands have an optional parameter that is separated from the command by whitespace.

Warning.png Important: Case is significant in the command characters.

To execute a command programmatically, place it in a string and use the value function.

        value "\\p 5042"
Warning.png Note: A backslash in the string must be escaped.

Tables (\a)

The command \a returns a list of symbols with the names of all tables in the current context. For example, in a fresh q session,

        t:([]c1:1 2 3; c2:`a`b`c)
        \a
,`t

Console (\c)

The command \c (note lower case) controls the size of the q virtual console display. The first parameter specifies the number of rows and the second the number of columns. The default setting is 23 by 79.

        til 100
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 ..

        \c 23 200
        til 1000
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29
30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56
 57 58 59 60 61 62 63 64 65 66 67 68 ..

Web Console (\C)

The command \C (note upper case) controls the size of the q web console display. The first parameter specifies the number of rows and the second the number of columns. The default setting is 36 by 2000.

Change O/S Directory (\cd path)

The \cd command affects the current working directory of the underlying operating system. To display the current directory, issue \cd with no argument.

        \cd
"/Users/jeffry/bin"

The result of \cd is the text string as received from the O/S with escapes where applicable. For Windows, the back-slash characters are escaped and are not converted to forward-slashes.

To change the current working directory, issue \cd with the path of the desired directory.

        \cd /q

If the specified directory does not exist, it will be created.

Warning.png Note: Since the argument of \cd is not a string, special characters do not need to be escaped.

Directory (\d)

The \d command controls the current context (directory).

To determine the current context, issue \d with no parameter.

        \d
`.

To set the current context, issue \d followed by the target context.

        \d .tutorial
        \d
`.tutorial
Warning.png Note: If the specified context does not exist, using it in \d will cause its creation.

Issue \d . to set the current working context to the default context.

        \d .
        \d
`.

Functions (\f)

The \f command returns a sorted list containing the functions in a context (directory). When used with no parameters, it returns the functions in the current context.

        \f
`s#`diff`f`g

Use \f with the name of a context to list its functions.

	\f .debug
`s#``addBPs`break`clearBPs`deleteBPs`stop

Load (\l)

A script can be loaded at startup of q or during a session. To load the script from the session, issue the \l command with the (optionally qualified) name of the script file.

For example, to load the distribution script sp.q from the current directory,

        \l sp.q
+`p`city!(`p$`p1`p2`p3`p4`p5`p6`p1`p2;`london`london`london`london`london`lon..
(+(,`color)!,`blue`green`red)!+(,`qty)!,900 1000 1200
+`s`p`qty!(`s$`s1`s1`s1`s2`s3`s4;`p$`p1`p4`p6`p2`p2`p4;300 200 100 400 200 300)

Offset (\o)

The \o command sets the offset in hours from GMT used to determine local time in. For example,

        .z.z
2007.04.12T11:31:13.352
        .z.Z
2007.04.12T07:31:15.365

        \o -2

        .z.z
2007.04.12T11:31:35.954
        .z.Z
2007.04.12T09:31:37.587

Port (\p)

The \p command controls which port the kdb+ server listens on. For example,

        \p 5001

means that it will listen for connections on port 5001.

Warning.png Note: When you issue the \p commend, kdb+ attempts to open the port. For this to be successful, the security settings of the machine must allow it.

If the port has not been set, you will see,

	\p
0

This means that no connection to this instance of kdb+ is currently possible because it is not listening on any port. You can also issue \p 0 to stop listening on any port.

Precision (\P)

The precision command \P (note the upper case) sets the display precision for floating point numbers to the specified number of digits.

The default precision is 7, meaning that the display of float or real values is rounded to the seventh significant digit.

        \P
7

        f:1.23456789012345678
        f
1.234568

Set the precision with a non-negative int parameter.

        \P 12
        f
1.23456789012

Set the precision to the maximum available that respects multiplicative tolerance with 0. This is currently the same as using 16.

        \P 0
        f
1.234567890123457

Set the precision to the maximum available with 17.

        \P 17
        f
1.2345678901234569

Seed (\S)

The \S (note upper case) sets the seed for pseudo-random number generation. The default value is -314159. The argument is an integer.

        \S
-314159

        \S 424242
        \S
424242

Timer (\t)

The \t command controls the timer. The optional parameter is the number of milliseconds between timer ticks, with 0 signifying that the timer is off. On each timer tick, the function .z.ts is invoked if it has been assigned.

To determine the current timer setting, issue \t with no parameter.

        \t
0

To set the timer, issue \t with the number of milliseconds. For example, to set the timer to tick once a second,

        \t 1000
Warning.png Note: The actual timer tick frequency is determined by the timing granularity supported by the underling operating system. This can be considerably less than a millisecond.

To turn the timer off,

        \t 0

Elapsed Time (\t expr)

When the \t command is invoked with an expression as its parameter, the expression is evaluated and its duration of execution is reported. This can be used to profile code execution when tuning an application.

In q there are often multiple ways to achieve a desired result, but one may execute significantly faster. This may not matter for small tables or sporadic updates, but for processing very large volumes of data in real time it can be essential. Inserting \t at key points in the program can identify the critical routines that are consuming the most time. By measuring the execution times of alternate expressions for the critical routines, you can determine which is most efficient in your environment.

The following measures the time required to add the first 100,000 integers 10,000 times on the author's laptop.

        \t do[10000; sum til 100000]
2553

We conclude that adding the first 100,000 integers once requires approximately .25 milliseconds.

If it is actually necessary to add the first 100,000 integers in an application, you could use the formula,

        sn = (n*n-1)%2

We time it for n = 100,000.

        \t do[10000; (100000*99999)%2]
10

As you can see, this is roughly 200 times faster than performing the actual addition. We can do even better by replacing the division with a multiplication,

        sn = .5*n*n-1

To see the effects clearly, we increase the counter to 100,000.

        \t do[100000; sum til 100000]
25216
        \t do[100000; (100000*99999)%2]
120
        \t do[100000; .5*100000*99999]
80

Timeout (\T)

The \T command (note upper case) controls execution timeout. The int parameter is the number of seconds any call from a client will execute before it is timed out and terminated. The default value is 0 which means no timeout.

Variables (\v)

The \v command returns a sorted list containing the variables in the current context (directory). When used with no parameters, it returns the variables in the current context.

        \v
`s#`L`h`kt`p`pi`r`sqrt2`t`tdetails`third

Use \v with the name of a context to list its variables.

        \v .debug
`s#`breakPoints`stopPoints

Workspace (\w)

The workspace command \w (note lower case) displays six integer values that indicate memory usage by the current workspace.

        \w
168144 67108864 67108864 0 0 8589934592j

The first value indicates the number of bytes currently allocated. The second indicates the total number of bytes available in the heap. The third indicates the maximum heap seenn so far in the current session. The fourth indicates the maximum bytes available if set with the -w command line option, else 0. The fifth display the bytes mapped. The sixth displays the physical memory.

Week Offset (\W)

The week offset command \W (note upper case) specifies the start of week offset. An offset of 0 corresponds to Saturday. The default is 2, which is Monday.

Expunge Handler (\x)

The expunge handler command \x deletes the assignment of a user-specified function to one of the .z.p* event handlers and restores the default behavior. For example, if you have assigned a routine to .z.pc in order to process remote connection close, reset with,

        \x .z.pc

Date Format (\z)

The date format command \z specifies the format for date parsing. A value of 0 corresponds to mm/dd/yyyy; a value of 1 corresponds to dd/mm/yyyy.

        \z
0

        "D"$"12/31/2007"
2007.12.31

        "D"$"31/12/2007"
0Nd

        \z 1
	"D"$"12/31/2007"
0Nd

        "D"$"31/12/2007"
2007.12.31

Operating System (\text)

If a backslash is followed by characters not recognized as a kdb+ command, the text is assumed to be an operating system command and is passed to the O/S for execution.

For example, you can issue,

        \dir				/ display Windows directory
(" Volume in drive C has no label.";" Volume Serial Number is E89F-3533";..

        \pwd				/ display Unix directory
"/Users/jeffry/bin"

Any return value from the O/S is displayed as a list of strings.

Interrupt (Ctrl-C)

You can terminate a long-running routine by pressing the Ctrl-C combination.

Terminate (\)

The terminate command, denoted by a single backslash (\), exits one level of the q interpreter. This is useful when debugging a failed function evaluation. In the following console shot, we do not suppress the q prompt.


        q)f:{x*y}
        q)f[2;`3]
{x*y}
'type
*
2
`3
        q))\
        q)_

Here the underscore denotes the blinking cursor.

Information.png Advanced: If you issue \ at the "q)" prompt, you drop into a k session.
        q)\
_

Again, the underscore denotes the blinking cursor. Because k is q's underlying implementation language, some q expressions will execute as expected in the k session but most will not. Explanation of k is beyond the scope of this manual.

To return to the q console from a k session and see the "q)" prompt again, enter a single \ at the prompt.

 	\
q)

Exit Q (\\)

To exit the q process, enter a double backslash (\\),

	\\
Warning.png Important: There is no confirmation prompt for \\. The q session is terminated with extreme prejudice.

System Variables

Variables in certain reserved contexts provide useful q environmental interaction.

IP Address (.z.a)

The variable .z.a is an int representing the IP address of the current running kdb instance. To see the usual four-integer IP address, decode the int using base 256. For example, on the author’s laptop,

        .z.a
-1442929031
        `int$0x00 vs .z.a
169 254 166 121

Dependencies (.z.b)

The systen variable .z.b is a dictionary that represents variable dependencies. Recall that non-local assignment with :: establishes a dependency between the variable and variables in the expression assigned to it. These dependencies are recorded in the dictionary .z.b that maps a variable name to a list of the names of variables that depend on it.

For example, in a new q session, we find,

        a:42
        b:98
        c::a+b
        .z.b
a| c
b| c

Global Date (.z.d)

The variable .z.d retrieves the date component of Greenwich Mean Time (GMT) and is equivalent to,

        \`date$.z.z

Local Date (.z.D)

The variable .z.D retrieves the local date component from the local datetime and is equivalent to,

        `date$.z.Z

Startup File (.z.f)

The system variable .z.f is a symbol representing the name of the file or directory provided on the command line when the running instance of q was invoked. For example, if q is invoked from the O/S console with,

        q.exe convertargs.q 42 forty 2.0

we find,

        .z.f
`convertargs.q
        .z.x
("42";"forty";"2.0")

Host (.z.h)

The variable .z.h is a symbol representing the name of the host running the q instance.

        .z.h
`macpro.local

Process ID (.z.i)

The system variable .z.i is an int representing the process id of the running q instance.

        .z.i
8615
Warning.png Note: As of this writing (Jun 2007), .z.i is not yet implemented on Windows.

Release Date (.z.k)

The system variable .z.k is a date value representing the release date of the running kdb+ instance.

        .z.k
2006.06.01

Release Major Version (.z.K)

The system variable .z.K is a float value representing the major version of the running kdb+ instance.

        .z.K
2.4

License Information (.z.l)

The variable .z.l is a list of strings containing information about the license of the running kdb+ instance. The most useful are the items in positions 1 and two which represent the expiry date and update date, respectively.

#1q
        .z.l
("";"2007.07.01";"2007.07.01";,"1";,"1";,"0";,"0")

O/S (.z.o)

The system variable .z.o is a symbol representing the underlying operating system. For example, this tutorial is being written on a 64 bit Mac system.

        .z.o
`m64

Process Close (.z.pc)

The variable .z.pc is a q function representing an event handler that is executed whenever a connection to the current q process is closed. See Interprocess Communication for a discussion.

To reset the .z.pg to the default behavior, issue the command,

        \x .z.pc

Process Get (.z.pg)

The variable .z.pg is a q function representing an event handler that is executed whenever a client q process makes a synchronous call to the current q process. The name derives from the fact that an asynchronous call has get semantics. See Interprocess Communication for a discussion.

To reset the .z.pg to the default setting, issue the command,

        \x .z.pg

Process HTTP Get (.z.ph)

The variable .z.ph is a q function representing an event handler that is executed whenever an HTTP get is routed to the current q process. See Interprocess Communication for a discussion.

To reset the .z.ph to the default setting, issue the command,

        \x .z.ph

Process Input (.z.pi)

The variable .z.pi is a q function representing an event handler that is executed when q echoes the result of user input to the console. You can make the console display mimic that of 2.3 by assigning,
	.z.pi:{-1 .Q.s1 value x}

You can make the console display mimic that of 2.4 by assigning,

	.z.pi:{-1 .Q.s value x}

To reset the .z.pi to the default setting, issue the command,

	\x .z.pi

Process Open (.z.po)

The variable .z.po is a q function representing an event handler that is executed whenever a connection to the current q process is opened. See Interprocess Communication for a discussion.

To reset the .z.po to the default setting, issue the command,

        \x .z.po

Process HTTP Post (.z.pp)

The variable .z.pp is a q function representing an event handler that is executed whenever an HTTP post is routed to the current q process.

To reset the .z.pp to the default setting, issue the command,

        \x .z.pp

Process Set (.z.ps)

The variable .z.ps is a q function representing an event handler that is executed whenever a client q process makes an asynchronous call to the current q process. The name derives from the fact that an asynchronous call has set semantics. See Interprocess Communication for a discussion.

To reset the .z.ps to the default setting, issue the command,

        \x .z.ps

Global Time (.z.t)

The variable .z.t retrieves the time component of Greenwich Mean Time (GMT) and is equivalent to,

        `time$.z.z

Local Time (.z.T)

The variable .z.T retrieves the time component of Greenwich Mean Time (GMT) and is eqivalent to,

	`time$.z.z

Timer Expression (.z.ts)

The variable .z.ts is a q function representing an event handler that is executed on every timer tick (see the command \t). For example, the following displays local time to the console approximately every two seconds.

        .z.ts:{0N!`time$.z.Z}
         \t 2000
07:20:00.329
07:20:02.332
07:20:04.335
...

User (.z.u)

The variable .z.u is a symbol representing the user id that invoked the running q instance.

         .z.u
`Jeffry

Value Set (.z.vs)

The variable .z.vs is a q function representing an event handler that is executed whenever any global variable in root namespace is assigned in q. You could use .z.vs, for example, to monitor who is modifying certain variables.

The signature of the handler is,

	{[v;i]...}

where v represents a symbol with the name of the variable being assigned and i is the index for which the assignment is applied. The following trivial handler displays v and i to the console.

        .z.vs:{[v;i]0N!v;0N!i;}
        a:42
`a
()

        a:til 5
`a
()

        a[2]:42
`a
,2

        a[0 3]:6
`a
,0 3

Since the granularity of .z.s is all or nothing, you'd need to write your own logic to monitor only certain variables, for instance.

To remove the handler, issue the command \x .z.vs.

        \x .z.vs
        a:42
_

Handle (.z.w)

The variable .z.w contains an int with the connection handle (i.e., “who”) during synchronous or asynchronous request processing. See Interprocess Communication for a discussion.

Command Line Parameters (.z.x)

The system variable .z.x is a list of strings representing the command line parameters provided after the name of the file or directory on the command line when the running instance of q was invoked. For example, if q is invoked from the O/S console with,

        q.exe convertargs.q 42 forty 2.0

we find,

        .z.f
`convertargs.q
        .z.x
("42";"forty";"2.0")

GMT (.z.z)

The variable .z.z is a datetime value representing the current Greenwich Mean Time (GMT) as reported by the operating system.

	.z.z
2007.02.02T15:24:28.156

Local Date and Time (.z.Z)

The variable .z.Z is a datetime value representing the current local time as known to the operating system.

	.z.Z
2007.02.02T10:24:30.820
Warning.png Note: The -o startup option or \o command override the default time zone offset as determined by the operating system. This is useful when you want to adjust time manually, such as for daylight savings time.

Command Line Parameters

We describe here the options of a q session that can be set via command line parameters. A command line parameter is deonted by a dash (-) and a single character, followed by whitespace and then the valu(s) of the parameter. Multiple command line characters are separated by whitespace and can be entered in any order.

Warning.png Note: The case of the command line character is significant.

Most command line parameters have equivalent workspace commands denoted by the same character. See Command Format (\d) for detailed descriptions and examples.

Console (-c)

The console parameter is a pair of ints that specify the size of the q virtual console display. The first specifies the number of rows and the second the number of columns. The default setting is 23 by 79. This parameter corresponds to the command \c.

Web Browser Console (-C)

The web console parameter (note upper case) is a pair of ints the specify the size of the q web console display. The first parameter specifies the number of rows and the second the number of columns. The default setting is 36 by 2000. This parameter corresponds to the command \C.

Offset (-o)

The offset parameter is an int that sets the offset in hours from GMT used to determine local time in .z.Z. This parameter corresponds to the command \o.

Port (-p)

The port parameter is an int that specifies the port number on which the kdb+ server listens. This parameter corresponds to the command \p.

Print Digits (-P)

The print digits parameter is an int that specifies the display precision for floating point numbers to the specified number of digits. The default precision is 7, meaning that the display of float or real values is rounded to the seventh significant digit. This parameter corresponds to the command \P.

Timer (-t)

The timer parameter is an int that specifies the number of milliseconds between timer ticks, with 0 signifying that the timer is turned off. This parameter corresponds to the command \t.

Timeout (-T)

The timeout parameter (note upper case) is an int that specifies the number of milliseconds any call from a client will execute before it is timed out and terminated. The default value is 0 which means no timeout. This parameter corresponds to the command \T.

Workspace Size (-w)

The workspace parameter is an int that specifies the maximum workspace size in megabytes. The default value is unlimited. A value of 0 means an unlimited workspace. In a multithreaded mode, as each thread has its own heap, this limit is per thread and not per process.

Week Offset (-W)

The week offset parameter (note upper case) is an int that specifies the start of week as an offset from Saturday. For example,

	q –W 2

starts a q session in which Monday is considered the beginning of the week.

Date Format (-z)

The date format parameter is a boolean value that specifies the format expected in date parsing. A value of 0 corresponds to mm/dd/yyyy; a value of 1 corresponds to dd/mm/yyyy. This parameter corresponds to the command \z.


Prev: Workspace Organization Next: Built-in Functions

Table of Contents

©2006-2007 Kx Systems, Inc. and Continuux LLC. All rights reserved.

Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox