Runtime (annex)

.z, .Q, .j, system commands: documented, not required

Annex — not required One chapter of the Open Q Language specification. README.txt states what must be implemented and how conformance is defined.

This surface is documented because a runtime author needs to know what .z.pw is for, and a user needs to know where .Q.fs comes from. It is NOT normative because pinning it would exclude every real implementation, including kdb+'s own past and future versions: local time depends on the host, workspace limits on the machine, timer granularity on the scheduler, and .Q's membership changes between releases.

No rule here is REQUIRED for conformance. Where a rule is nonetheless stable enough to pin — .j.j / .j.k round-tripping, for instance — the corpus tests it like any other and those tests count. What is never asserted is anything marked IMPLEMENTATION-DEFINED below: those are the behaviours that genuinely cannot be fixed without naming a host, a machine, or a release.

RT-00011. The .z namespace

.z holds process environment values and event callbacks. It divides sharply in two, and the division is the part worth knowing.

RT-00021.1 Environment values: always defined

These resolve at any time and are computed on access, not stored.

p P     current timestamp, UTC / local
d D     current date,      UTC / local
t T     current time,      UTC / local
z Z     current datetime,  UTC / local
n N     current timespan,  UTC / local
x       command-line arguments after the script (parse with .Q.opt)
f       the script file currently being loaded
h       hostname
k       the version date of the implementation
K       the major version number
i       process id
o       operating system / build identifier
u       the user
w       workspace usage
a       IP address
b       dependency information
c       console size
e       TLS connection status
W       open handles

IMPLEMENTATION-DEFINED: the local-time values (P D T Z N) depend on the host timezone; the corpus contains no local-time expression for exactly this reason. o, k, K, h, i, u and a are properties of the process, not of q.

RT-00031.2 Callbacks: undefined until assigned

A callback name does not exist until something sets it. Reading one that has not been set signals; it does not return a null or a default handler.

ts          timer, fired by \t
pg ps       incoming sync / async message
po pc       connection opened / closed
pw          authentication: (user;password) -> boolean
ph pp       HTTP GET / POST
pi pm       input / monitor hooks
ws wo wc    websocket message / open / close
pd          peach handle list
zd          compression settings (blockSize;algorithm;level)
exit        run on process exit
vs ac bm ex ey pq s
            assorted hooks; s is the self-reference, meaningful only
            inside a function

Verified against the reference: every name in 1.1 resolves in a fresh process and every name in 1.2 does not.

RT-00041.3 key `.z does not enumerate .z

Because the environment values are computed rather than stored, the namespace dictionary is nearly empty — a fresh reference process reports only the empty symbol and whichever callbacks happen to be set. A tool that discovers .z by listing its keys will find almost nothing. Probe by name.

RT-00052. The .Q namespace

.Q is the utility namespace: roughly 180 members in the reference, and unlike .z it IS enumerable with key `.Q.

The ones a portable program actually depends on:

opt         parse .z.x into a dictionary of options
en ens      enumerate a table's symbol columns against a sym file
            (storage.txt 3.2 — writing a splayed table needs this)
dpft dpfts  write a partitioned table, set the parted attribute
chk         repair a partitioned database
par         resolve a partition path, honouring par.txt
fs fsn      stream a file through a function in chunks
hg hp       HTTP get / post
gc          trigger garbage collection
s s1 s2     the show/display forms
addmonths   calendar arithmetic
f fmt       number formatting
trp trpd    trap with a backtrace
A a n b6    character and digit constants

IMPLEMENTATION-DEFINED: membership. .Q grows between releases and much of
it is internal (single- and double-letter names are largely private
machinery). A runtime that implements the list above is portable in
practice; one that implements all 180 is matching an implementation, not a
language.

RT-00063. The .j namespace

JSON, and small enough to state completely. The reference defines exactly:

j   value -> JSON text
k   JSON text -> value
J   e   es   jd   q   s

j and k are the pair that matters and are the ones the corpus pins
(16_json). JSON has no q type for every q type, so the round trip is lossy
in the obvious ways: symbols and strings both become JSON strings, and
temporal types become text.

RT-00074. System commands

A line beginning with \ is a system command (core.txt 3.12). The portable set:

\l file     load a script or a database directory
\p [n]      listen on a port; \p 0 binds an ephemeral one; \p shows it
\t expr     time an expression, in milliseconds
\t n        set the timer interval, firing .z.ts
\ts expr    time and space
\c r c      console size (rows, columns)
\P n        float display precision
\e n        error trapping mode
\s n        secondary threads
\w          workspace usage; \w n sets the limit
\x name     delete a .z callback, restoring the unset state
\\          exit

IMPLEMENTATION-DEFINED: \s thread counts, \w limits, \t granularity, and
the console default all depend on the machine. \P changes DISPLAY only —
see core.txt 11: value equality does not depend on it, which is why the
conformance corpus does not set it.

RT-00085. Why this is an annex

Documented-but-not-required is a deliberate third state, distinct both from "specified" and from "absent".

A runtime that implements none of section 1.2 is still a conformant q implementation for the language; it is simply not a q SERVER. A runtime that implements .z.pw differently from kdb+ is not wrong, because there is nothing here for it to be wrong about. No corpus test asserts a callback's behaviour, so declining to be a process host costs a runtime nothing on the scorecard.

Source: spec/runtime.txt