Source: https://code.kx.com/q4m3/13_Commands_and_System_Variables/
Timestamp: 2019-04-24 08:21:13+00:00

Document:
Commands control aspects of the q run-time environment. A command begins with a backslash \ followed by the command name. Many commands have optional parameter(s) separated from the command name by a blank (multiple blanks or other whitespace characters are not permitted). Case is significant in the command name.
Commands whose parameter refers to a namespace apply to the current working context if the parameter is omitted.
You could execute a command programmatically by placing it in a string as an argument to value. Observe that you must escape the \ in the string.
q)value "**Error! Hyperlink reference not valid.**" / bad practice!
Never do this in production – it exposes your system to all manner of attacks!
Instead use the built-in system that at least checks for a valid command. Note that it also eliminates the backslash and hence the need to escape it.
See §13.3.3 for the related .z.b.
0  1  2  3  4  5 ..
10 11 12 13 14 15 ..
The \cd [path] command is passed directly through to the OS. To display the current directory, issue \cd with no argument.
To change the current working directory, issue \cd followed by the path of the desired directory. If the specified directory does not exist, q displays the error message from the OS.
The \cd command creates the directory if it does not exist. For example, the directory /data is initially empty.
The \d [namespace] command displays or changes the current context (a.k.a. directory in early versions of k). To determine the current context, issue \d with no parameter. In a fresh q session this will be the root. To change the current working context, include its namespace with the \d command. If the specified context does not exist, it will be created.
See our recommendations against using \d in §12.7.
The \e [0|1] command displays or changes the behavior of a q process when an exception occurs during processing a client (i.e., remote) IPC request.
In a fresh q session the default is 0, meaning that when an exception occurs the stack of the failing function is cleared and execution continues. This is the desired behavior for a production server, as you do not want wayward client requests to disable the process.
In a development or testing scenario you can set this value to 1 to enable the familiar stack trace from the interactive console.
Following is a description of q/kdb+ memory management provided by Charles Skelton, the Kx CTO.
Q/Kdb+ manages its own thread-local heap.
Vectors always have a capacity and a used size (the count).
There is no garbage since q/kdb+ uses reference counting. As soon as there are no references to an object, its memory is returned to the heap.
During that return of memory, q/kdb+ checks if the capacity of the object is >=64MB. If it is and \g is 1, the memory is returned immediately to the OS; otherwise, the memory is returned to the thread-local heap for reuse.
Executing .Q.gc additionally attempts to coalesce pieces of the heap into their original allocation units and returns any units >=64MB to the OS.
Beginning with 3.3 2015.08.23 – Linux only – unused pages in the heap are dropped from RSS during .Q.gc.
When q/kdb+ is denied additional address space from the OS, it will invoke .Q.gc and retry the request to the OS. Should that fail, it will exit with 'wsfull.
When slave threads are configured and .Q.gc is invoked in the main thread it will automatically invoke .Q.gc in each slave thread. If the call is instigated in a slave thread – i.e., not the main thread – it will affect that thread’s local heap only.
See §13.2.5 for the related command line parameter -g.
When something is recognized as a q resource, the loading routine does what is appropriate to make that resource available in the workspace.
When something is not a recognized q resource, it fails.
A file can be a serialized q entity – e.g., the sym file for a splayed or partitioned table. In this case, the entity is deserialized into memory into a variable having the name of the file.
The situation for a directory is more complicated.
The directory of a splayed table is mapped into memory with the name of the directory as the table name. None of the actual table data is actually loaded into memory at this time.
For a directory name that is the value of one of the permitted partition types, the most recent partition directory is inspected for splayed directories and each such directory is mapped into memory with the name of the splayed directory.
The root of a kdb+ database can contain: serialized q entities (e.g., the sym file), scripts (e.g., a start-up script), splayed table directories, partition directories or a par.txt file. In this case, the loading routine simply “does” each entity that it finds, as outlined above. The scripts are executed last.
When a directory is mapped, the current working directory in the OS is set to that directory. This allows relative paths to subordinate items in the database and also helps to avoid wayward operations.
Once you have mapped a database into memory, you can issue the command \l . to remap the data without executing any start-up script(s) in the root.
The \o [offset] command displays or changes the offset from GMT for q date/time values in the current q session. When the absolute value of the integer offset is strictly less than 24 it is interpreted as hours; if it is 24 or greater it is interpreted as minutes.
In a fresh q session, the value is 0Ni, meaning that the underlying OS time zone offset is used.
See §13.2.7 for the related command line parameter -o.
When you issue the \p command, q attempts to open the port but the security settings of your machine must allow it.
Once you open a port, that q session is wide open to all connections, including to HTTP traffic. We strongly recommend that you implement appropriate security around any process with an open port in a production environment.
See §13.2.8 for the related command line parameter -p.
The command \P[precision] (note upper case) shows or sets the display precision for floating point numbers – i.e., float and real types – to the specified number of digits.
Only the display of the floating point values is affected. The internal representation remains unchanged.
Notice the schmutz in the 17th significant digit. This is part of the dark mystery of binary floating point that is not mentioned in polite company.
You can use the semi-official functions .Q.f and .Q.fmt for controlled formatting of floating point values as strings.
See §13.2.10 for the related command line parameter -P.
The replication command \r is reserved for system use when using replicating servers. Do not use manually.
See §13.2.12 for the related command line parameter -r.
The \s command displays the number of slaves available to the current q process. Read only. See §13.2.13 for setting this value with the command line parameter -s.
The \S [seed] command (note upper case) displays or sets the initial seed for pseudo-random number generation to the integer value seed. This is useful for obtaining repeatable results from randomized testing. The default value is -314159.
In a simple q session without slaves and multi-threaded input, the behavior is simple. Resetting the seed to the default value allows the pseudo-random values to be reproduced.
When the q process is not started in single-threaded mode, things are more complicated.
When the q process is started with a positive number of slaves, each slave gets its own seed (set internally) based on the slave number.
When the process is started in multi-threaded input mode, each thread gets a seed based on the socket descriptor.
When the process is started with negative slaves, each process on a specified range of ports gets its own seed based on the port number.
The \t command has two interpretations, depending the type of its parameter. When \t [millis] is issued with a positive integer argument, it sets the number of milliseconds between timer ticks. The default value is 0i, meaning that the timer does not fire. Setting to a non-zero value starts the timer, which will fire after the specified number of milliseconds Reset to 0i to turn it off.
The actual timer tick frequency is determined by the timing granularity supported by the underling operating system. This can be considerably different from a millisecond.
See §13.2.14 for the related command line parameter -t.
When \t expr is issued with a valid q expression, the expression is evaluated and the execution duration in milliseconds is reported. This can be used to profile code execution when tuning an application.
Some expressions execute so quickly in q that the result is less than the timer granularity. Fortunately \t:x obviates what was formerly the only valid use of do in q – namely, repeating the expression evaluation to raise its execution time above the timer floor.
We conclude that adding the first 100,000 integers once requires approximately .45 milliseconds.
Of course you would never evaluate this exact expression in practice; instead, use the insight of the young Gauss.
The \ts expr command is an enhancement of the version of \t that times an expression. It provides both the time and the number of bytes used in evaluating the expression.
You can also specify the number of repetitions, as with \t.
The \T secs command (note upper case) sets the number of seconds a remotely initiated execution will run before timing out. The default value is 0, meaning that such execution will not timeout. This is useful to protect against runaway client calls when the q process is acting as a server.
See §13.2.15 for the related command line parameter -T.
When the q process has been started with the –u command to load a password file, the \u command reloads the password file. This allows the password to be changed while the process is running.
See §13.2.17 for the related command line parameter -u.
The expunge handler command \x handler un-assigns a user specified event handler for one of the .z.* event handlers and restores the default system behavior. For example, here is how you can customize the console response and then restore the original behavior.
There is no default handler for .z.ph so expunge does not work there.
See §13.2.21 for the related command line parameter -z.
The \_ command with no parameter checks to see if client write access is blocked. See the description of –b in §13.2.1.
The _ script.q command transforms the specified script file into an equivalent one in script.q\_ that can be loaded and executed with \l but whose contents are scrambled for human eyes. The resulting file cannot be viewed, serialized or modified.
For example, suppose we have saved the following script as /scripts/sensitive.q.
Then we can lock it as follows.
If oscmd results in an operating system error, an exception will be thrown in q. For safe programmatic execution, you can trap the exception by executing oscmd with system wrapped in protected evaluation.
You can interrupt a long-running q function with Ctl-c. Note that some q functions are so tight that the interrupt may not be registered. You can terminate any q console session with extreme prejudice using Ctl-z, which will result in all contents of the workspace being lost.
Use \ to terminate one level of suspended execution arrived at via an exception.
Do not have an itchy trigger finger when exiting multiple levels of suspended evaluation, as \\ will exit the q session immediately.
If you are adventuresome, you can also issue \ at the normal q console prompt to toggle between the q interpreter and the k interpreter.
To exit the q process, enter a double backslash \\ at any console prompt.
There is no confirmation prompt for \\. The q session is terminated with extreme prejudice.
For programmatic q shutdown, use exit with a return value, which can be piped into other processes.
When you start q from the command line, you can optionally follow the q executable immediately with a file or directory to be “loaded” upon startup. This is effectively the same as issuing the \l command with that file or directory as the first action in the q session.
Following the q executable and the file name, you can include one or more command-line options. Each is prefaced with - and followed by whitespace and an optional parameter value. Many of the command-line parameters have equivalent q commands that can be issued within the session.
The –b command line parameter disallows connected clients to modify data. This includes setting global variables or modifying files.
This behavior is only in effect for operations initiated via remote (i.e., client) connection, so you will not see the effects in a console session on the server process.
The –c r c parameter specifies a pair of integers for the size of the q virtual console display as rows and columns. The default size is 25 80i.
The –C r c parameter (note upper case) specifies a pair of integers for the size of the HTTP virtual console display as rows and columns. The default setting is 36 by 2000.
The -e0|1 parameter enables or disables trapping exceptions arising during processing IPC requests. The default is 0.
The -g0|1 parameter sets the garbage collection behavior. See §13.1.8 for an explanation.
The -l parameter starts q with logging of remote requests enabled. Following is a brief description of how logging works; see the Kx site for more information. The –L parameter (note upper case) forces disk write on each remote execution.
will use files /data/logdemo.log and /data/logdemo.qdb.
The idea of logging is that each time a remote request is executed, it is logged. Periodically the application issues the \l command to checkpoint the current state of the workspace (more specifically, to serialize and persist the root context) and clear the log.
Should a logging process terminate abruptly, restarting it with the same –l command causes the most recently persisted state to be restored. Specifically, the serialized root context is restored from the .qdb file and requests that were processed after the state was persisted are replayed from the .log file.
Note that although only remote requests are logged, the process can ensure that its own activity is logged by sending requests to itself with the reserved handle 0.
Here is a simple session that demonstrates the logging scenario using local activity. Remote activity works the same.
The –o offset parameter specifies the offset from GMT for q time values. See §13.1.10 for an explanation.
The –p portnum parameter opens portnum for TCP/IP and HTTP traffic. The default is 0 meaning that no port is open.
Only one port can be open in a given q session.
The –p -portnum parameter starts the q session in multithreaded mode. See the Kx site for information on how this works.
The –P digits parameter (note upper case) specifies the number of digits for floating-point display. See §13.1.12 for an explanation.
The –qparameter starts q quietly, meaning that no start-up banner is displayed and there is no q prompt at the console.
The –r parameter starts a replicating q server. See the Kx web site for information on replication.
The –s N parameter starts the q process with N slaves for concurrent execution. See the Kx web site for information on slaves.
The –t millis command specifies the number of milliseconds between timer ticks. See §13.1.17 for an explanation.
The –T secs parameter specifies the number of seconds for timeout of remote requests. See §13.1.20 for an explanation.
The –u 1 parameter disables calling out to the OS via system.
The –u filename parameter starts a q session with a file of user names and passwords that will be checked when a remote connection requests is received. The remote connection has no access outside the database root directory.
The –U filename parameter (note upper case) starts a q session with a file of user names and passwords that will be checked when a remote connection requests is received. No restriction is placed on file system access by remote connections.
The –w bytes parameter specifies the maximum virtual size of the workspace in bytes. Any attempt to allocate more than this amount of memory will result in a 'wsfull exception and immediate termination of the q process. The default is twice the amount of physical machine memory.
The –W offset parameter (note upper case) sets the offset of the beginning of the week relative to Saturday. See §13.1.24 for the related \w command.
The –z 0|1 parameter specifies the date parsing format. See §13.1.26 for details in the related \w command.
Variables in the .z namespace reflect q environmental information and behavior.
Note that .z.ac supersedes .z.pw when defined.
The system variable .z.b is a dictionary that represents the (direct) dependencies of all aliases. The keys are symbolic names of entities in the workspace and the associated values are lists of symbolic names of entities that depend directly on the entity named by the key.
It is a nice exercise to write a q expression that recursively finds all dependencies, not just direct ones. Another nice exercise is to invert the dictionary to relate the name of an entity to everything it depends on.
The system variable .z.c represents the number of cores on the physical machine hosting the q process. Hardware with hyper-threading reports the number of virtual cores.
The system variable .z.exit specifies a handler to be called just before the q process exits in order to clean up resources.
The handler cannot cancel the exit.
The parameter passed to the handler is 0i if the exit was invoked manually with \\ or it is the argument to the exit function when that was called programmatically.
Note that if the handler itself throws an exception – deliberate or otherwise – the session will be suspended at that error.
The default exit behavior can be restored by expunging with \x.
The system variable .z.d retrieves the date component of Greenwich Mean Time (GMT) and is equivalent to `date$.z.p.
The system variable .z.D retrieves the local date component according to the time zone offset from GMT and is equivalent to `date$.z.P.
As of this writing (Sep 2015), .z.i is not implemented on Windows.
The value of .z.l is () for 32–bit non-production versions of q.
The system variable .z.n retrieves the timespan component of Greenwich Mean Time (GMT) and is equivalent to `timespan$.z.p.
The system variable .z.N retrieves the local timespan component according to the time zone offset from GMT and is equivalent to `timespan$.z.P.
The system variable .z.o is a symbol representing the operating system hosting the current q process. For example, this text is being written on a 32-bit Mac system.
The system variable .z.p retrieves the current Greenwich Mean Time (GMT) with nanosecond resolution. It is the basis for all other date and time values in the .z namepsace.
The system variable .z.P displays the current local nanosecond resolution from .z.p according to the time zone offset.
Assign a q function to the system variable .z.pc to be invoked after a connection is closed – a.k.a. “process close.” At the point your handler is invoked, the other variables associated with the connection – e.g., .z.w – have already been wiped. The handle of the connection that has just been closed is passed as the lone parameter to your handler so that you can clean up any resources associated with it in your application.
To reset to the default setting, expunge the handler with \x .z.pc.
Assign an int list or q function representing an event handler to the system variable .z.pd for use by peach for a q process that has been started with the –s command line parameter with a negative value. Your handler supplies a list of ints representing open handles to other processes and will be called by peach when it distributes work to those processes. These handles must not be used for other processing as peach will close any handle that presents data it is not accepting. See §A.68.2 on distributed processing with peach.
The int return list of your handler must have the `u# attribute applied.
Here is a simple example that opens and returns five handles on the local machine starting at port 20000. It assumes that worker processes have already been started with these ports open. See the Kx site for more comprehensive examples.
Assign a function to the system variable .z.pg to be invoked whenever a remote client q process makes a synchronous call over an open connection – a.k.a. “process get.” The name derives from the fact that a synchronous call has get semantics. The default behavior applies value to the incoming message.
To reset to the default setting, expunge the handler with \x .z.pg.
Assign a function to the system variable .z.ph to be evaluated whenever a synchronous HTTP request is routed to the current q process – a.k.a. “process http.” See §11.7.1 for a discussion.
To reset to the default setting, expunge the handler with \x .z.ph.
Assign a function to the system variable .z.pi to be evaluated when q echoes the result of user input to the console – a.k.a. “process input.” For example, the following mimics the console display of pre-2.4 q versions.
To reset to the default behavior, expunge the handler with \x .z.pi.
Assign a function to the system variable .z.po to be evaluated after a connection to the current q process has been successfully opened – a.k.a. “process open.” See §11.6 for a discussion. The local handle of the connecting process is passed in the second parameter.
To reset to the default setting, expunge the handler with \x .z.po.
Assign a function to the system variable .z.pp to be evaluated whenever an HTTP post is routed to the current q process – a.k.a. “process post.” See §11.7 for a discussion of .z.pg, whose parameters are the same.
To reset the .z.pp to the default setting, expunge the handler with \x .z.pp.
Assign a function to the system variable .z.ps to be evaluated whenever a client process sends an asynchronous message to the current q process – a.k.a. “process set.” The name derives from the fact that an asynchronous call has set semantics. The parameter passed to your handler is the message content. The default behavior is to invoke value.
To reset the to the default setting, expunge the handler with \x .z.ps.
Assign a function to the system variable .z.pw to be evaluated after the command line –u and –U checks but before the .z.po handler – a.k.a. “password.” This can be used to implement authorization – i.e., who is allowed to do what. Your handler should accept two parameters: a symbolic user name and a password string. It should return a boolean pass/fail indicator.
To reset to the default setting, expunge the handler with \x .z.pw.
The system variable .z.q is a read-only boolean indicating whether q was started in quiet mode using the –q 1 command line parameter.
The system variable .z.s represents the current function during function evaluation. This can be useful when writing recursive functions but there is often a better way to do this using adverbs. For example, here is a stack-eating recursive factorial.
The system variable .z.t retrieves the time component of Greenwich Mean Time (GMT) and is equivalent to `time$.z.p.
The system variable .z.T retrieves the local date component according to the time zone offset from GMT and is equivalent to `time$.z.P.
Assign a function to the system variable .z.ts to be evaluated on every timer tick – see §13.1.18 for the command \t to start/stop the timer. For example, the following assigns a handler to display local time to the console, turns on the timer to fire (approximately) every two seconds and turns it off after a few ticks.
To restore the default behavior, expunge the handler with \x .z.ts.
The system variable .z.u is a symbol that represents the user ID of the q session.
Inside the processing of a remote message on a server, .z.u represents the user ID of the remote session.
To restore the default behavior, expunge the handler with \x .z.vs.
The system variable .z.w represents the handle of “who” is in communication during the current remote call. At the console prompt, the value is 0i, representing the interactive user. In the midst of processing a remote message, it is the (local) open handle associated with that remote client on this process.
The system variable .z.W (note upper case) returns a list of dictionaries whose keys are open handles and whose values are lists of bytes in the corresponding output queue. See the Kx site for more details.
Introduced in q3.3, the system variable .z.wc can be assigned a handler that is called when a WebSocket connection is closed. Prior to q3.3 this was handled in .z.pc.
Your handler is executed immediately after a WebSocket connection has been closed. Since the connection has been closed by the time the handler is called, there are no valid remote values for .z.a, .z.u or .z.w. Consequently the local values are returned.
This is useful to clean up things like a table of users keyed by handle, in which case you use the just-closed handle that is passed as a parameter to .z.wc.
Introduced in q3.3, the system variable .z.wo can be assigned a handler that is called when a WebSocket connection is opened. Prior to q3.3 this was handled in .z.po.
Your handler is executed just after a WebSocket connection to a kdb+ session has been initialized – i.e., once it has been validated against a -u/-U file (if specified) and .z.pw checks. The argument is the just-opened handle.
This handler is typically used to build a dictionary of handles associated with session information such as .z.a or .z.u.
Assign a function to the system variable .z.ws to be evaluated whenever a message arrives over a WebSocket. See §11.7 for examples.
The system variable .z.z retrieves the GMT date component and is equivalent to `datetime$.z.p.
This is deprecated in favor of .z.p.
The system variable .z.Z retrieves the local date component according to the timezone offset from GMT and is equivalent to `datetime$.z.P.
The system variable .z.zd displays or sets a list of parameters for data compression: logical block size, compression algorithm and compression level. For example, the following are reasonable settings.
See the Kx site for more details on the implementation of data compression.

References: §13
 §12
 §13
 §13
 §13
 §13
 §13
 §13
 §13
 §13
 §13
 §13
 §13
 §13
 §13
 §13
 §13
 §13
 §13
 §13
 §11
 §11
 §11
 §13
 §11